Handles `POST /v1/wallets/screen`.

Errors

Returns 401 without usable credentials, 422 for an unusable address, and 500 when a store fails. A repeated Idempotency-Key returns 200 with the original screening instead of screening again.

POST /v1/wallets/screen

Handles `POST /v1/wallets/screen`.

cURL

curl --request POST \
  --url https://qa.esectra.com/v1/wallets/screen \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "address": "<string>",
  "network": "<string>",
  "force_rescreen": true,
  "subject_id": "<string>"
}
'

200

{
  "address": "<string>",
  "decision": "ALLOW",
  "decision_id": "<string>",
  "evidence": [
    {
      "id": "<string>",
      "kind": "IMAGE",
      "location": "<string>",
      "retention_policy": "<string>"
    }
  ],
  "exposures": [
    {
      "category": "SANCTIONS",
      "relationship": "DIRECT",
      "source_provider": "<string>",
      "amount_exposure": {
        "base_units": 1,
        "decimals": 1
      },
      "attributed_entity": {
        "entity_type": "EXCHANGE",
        "name": "<string>",
        "sanctions_listed": true,
        "jurisdiction": "<string>"
      },
      "confidence": 123,
      "hop_distance": 1,
      "observed_at": "<string>",
      "percentage_exposure": 123
    }
  ],
  "mixer_signals": [
    "<string>"
  ],
  "provider": {
    "provider": "<string>",
    "screened_at": "<string>",
    "data_version": "<string>"
  },
  "reasons": [
    {
      "code": "<string>",
      "message": "<string>"
    }
  ],
  "review_status": "PENDING",
  "risk_level": "LOW",
  "sanctions_evidence": [
    {
      "digest": "<string>",
      "list_id": "<string>",
      "published_at": "<string>",
      "retrieved_at": "<string>",
      "source_url": "<string>",
      "version": "<string>"
    }
  ],
  "sanctions_signals": [
    {
      "match_kind": "LISTED_ADDRESS",
      "matched_value": "<string>",
      "program": {
        "authority": "OFAC",
        "list_name": "<string>",
        "program_code": "<string>"
      },
      "source_provider": "<string>",
      "subject": {
        "id": "<string>",
        "kind": "IDENTITY"
      },
      "confidence": 123,
      "hop_distance": 1,
      "matched_entity": "<string>",
      "observed_at": "<string>"
    }
  ],
  "screening_id": "<string>",
  "served_from_cache": true,
  "attribution": {
    "entity_type": "EXCHANGE",
    "name": "<string>",
    "sanctions_listed": true,
    "jurisdiction": "<string>"
  },
  "cache": {
    "age_seconds": 1,
    "provider_captured_at": "<string>",
    "source_screening_id": "<string>"
  },
  "case_id": "<string>",
  "provider_risk_score": 123
}

Authorizations

api_keysession_cookie

Authorization · string · header · required

A tenant API key. Acts for exactly one tenant and cannot conclude a case, because a conclusion records a person.

Body

application/json

Wallet screening request body.

address · string · required

Address to screen.

network · string · required

Network the address is on. Network the address is on, as a code such as ETHEREUM.

A string rather than the enum, so that a network this build does not screen reaches the handler and is refused by name. Typed as the enum it failed deserialization first, which returned a generic malformed-body error - indistinguishable from a typo, and giving an integration no way to tell "you sent rubbish" from "we do not cover that ledger".

force_rescreen · boolean

Ask the provider again instead of reusing a cached answer.

subject_id · string | null

Tenant's customer, when the wallet belongs to one.

Response

200

application/json

A replayed Idempotency-Key, or a cached screening

Wallet screening response body.

address · string · required

Address that was screened.

decision · enum<string> · required

Decision outcome. Sentinel recommends; it never enforces.

Available options: ALLOW, WARN, BLOCK, HOLD, REVIEW_REQUIRED, FLAG, BLOCK_RECOMMENDED, SUSPEND, END_STREAM

decision_id · string · required

Decision record identifier.

evidence · object[] · required

References to the retained raw provider response.

Show child attributes

exposures · object[] · required

Normalized risk exposures.

Show child attributes

mixer_signals · string[] · required

Mixer signals derived from the exposures.

provider · object · required

Provider and data version behind the screening.

Show child attributes

reasons · object[] · required

Explanation reasons.

Show child attributes

review_status · enum<string> · required

Review lifecycle state.

Available options: PENDING, APPROVED, OVERTURNED, NOT_REQUIRED

risk_level · enum<string> · required

Explainable risk level.

Available options: LOW, MEDIUM, HIGH, CRITICAL

sanctions_evidence · object[] · required

The sanctions publications this answer was reached against.

Present for a clean answer too: a customer being told an address is not designated needs to be able to say which publication that was decided against, and on what date it was retrieved.

Show child attributes

sanctions_signals · object[] · required

Sanctions signals.

Show child attributes

screening_id · string · required

Screening record identifier.

served_from_cache · boolean · required

Whether the answer was reused from the screening cache.

attribution · null | object

Entity the address is attributed to.

Show child attributes

cache · null | object

Where a reused answer came from, and how old it was.

Show child attributes

case_id · string | null

Review case opened for the decision, when one was needed.

provider_risk_score · number<float> | null

The provider's own score, an input signal only.